feat: add MCP migration helper and subagent connectivity pre-check by Tibsfox · Pull Request #814 · gsd-build/get-shit-done

Tibsfox · 2026-02-28T10:42:25Z

Summary

Add /gsd:migrate-mcp command that guides users through migrating project-scoped MCP servers (.mcp.json) to global scope (~/.claude/mcp.json) — the proven workaround for Claude Code bug #13898
Add <mcp_check> connectivity pre-check block to all 11 GSD agent definitions, preventing subagents from silently hallucinating MCP results when project-scoped servers are inaccessible
Implements BUG-5 (Global MCP Migration Helper) and the MCP Connectivity Pre-Check from the GSD Subagent Capability Inheritance analysis documented in docs/MCP-FRONTMATTER-FINDINGS.md

Root Cause

Claude Code bug #13898 prevents custom subagents (agents defined in .claude/agents/ or ~/.claude/*/agents/) from accessing project-scoped MCP servers configured in .mcp.json. When a subagent attempts to use an MCP tool (e.g., mcp__context7__*, mcp__slack__*), the call silently fails and the agent hallucinate results rather than reporting an error. Global MCP servers (~/.claude/mcp.json) propagate correctly to all agent types.

The mcpServers: frontmatter field was investigated as an alternative solution (see docs/MCP-FRONTMATTER-FINDINGS.md). While it works for project-specific agents in .claude/agents/, it cannot solve GSD's problem because GSD agents are generic templates installed globally — we cannot hardcode user-specific MCP server configurations into them.

Fix

Two complementary, defense-in-depth changes:

1. `/gsd:migrate-mcp` command (`commands/gsd/migrate-mcp.md`, +117 lines)

A guided 5-step interactive command that:

Reads the project's .mcp.json and displays discovered servers
Reads the user's global ~/.claude/mcp.json (if it exists)
Classifies each server as ADD / SKIP (already identical) / CONFLICT (same name, different config)
Presents a merge plan with trade-off warnings (global = available in ALL projects)
Performs the migration using the Write tool (not heredoc) and verifies the result

Handles edge cases: missing .mcp.json, empty configs, conflicting server names with interactive resolution, and idempotent re-runs.

2. MCP connectivity pre-check in all 11 agents (+12 lines each, +132 lines total)

Adds a <mcp_check> block after each agent's <role> or <project_context> section with four directives:

Check availability — attempt to call expected MCP tools before relying on them
Report clearly — if unavailable, stop and show the user the exact fix (/gsd:migrate-mcp)
Never hallucinate — treat failed MCP calls as connectivity issues, not data issues
Graceful fallback — continue without MCP if the task can use other tools (Read, Bash, WebSearch)

Agents modified: gsd-codebase-mapper, gsd-debugger, gsd-executor, gsd-integration-checker, gsd-phase-researcher, gsd-plan-checker, gsd-planner, gsd-project-researcher, gsd-research-synthesizer, gsd-roadmapper, gsd-verifier

Relationship to Other PRs

This is PR-1 of 6 from the dev-bugfix branch. It is the only PR that targets dev-bugfix (the others target main):

PR	Title	Target	Status
#1 (this)	MCP migration helper + connectivity pre-check	`dev-bugfix`	Open
#2	Milestone completion bugs	`main`	Open
#3	Cross-platform Windows CI	`main`	Open
#4	Feature enhancements	`main`	Open
#5	Agent frontmatter + heredoc fix	`main`	Open
#6	CLI/config bug fixes	`main`	Open

Merge order recommendation: Merge PR #5 to main first (adds mcpServers: frontmatter to agents), then merge dev-bugfix to main, then this PR to dev-bugfix. The <mcp_check> blocks added here do not conflict with PR #5's frontmatter additions — they modify different sections of the agent files.

Relationship to PR #5: PR #5 adds YAML frontmatter (including mcpServers: field support) and anti-heredoc instructions to agent files. This PR adds <mcp_check> blocks in the agent body. Both modify the same 11 agent files but in non-overlapping sections — frontmatter vs. body content.

Testing

/gsd:migrate-mcp is a prompt-based command (markdown instruction file), not executable code. It cannot be unit-tested. The test plan is manual:

Manual Test Plan

Run /gsd:migrate-mcp in a project with .mcp.json containing 2+ servers — verify it reads config, displays server table, presents merge plan, and writes to ~/.claude/mcp.json
Run /gsd:migrate-mcp in a project without .mcp.json — verify graceful "no servers found" message with guidance
Run /gsd:migrate-mcp when ~/.claude/mcp.json already has some servers — verify correct ADD/SKIP/CONFLICT classification
Run /gsd:migrate-mcp when project and global configs have identical servers — verify SKIP (idempotent)
Run /gsd:migrate-mcp when project and global configs have conflicting servers (same name, different config) — verify CONFLICT resolution prompt
Verify <mcp_check> block is present in all 11 agent .md files
Verify agents with MCP access (global scope) execute normally — no behavioral regression
Verify agents without MCP access report the issue clearly instead of hallucinating results
Spawn a subagent (e.g., gsd-executor) in a project with only project-scoped MCP — verify the pre-check catches it

Regression Test Suite

Full test suite passes with no regressions:

509 tests passed, 0 failed, 0 skipped
93 test suites
Duration: 4.96s

Test suites include agent frontmatter validation (47 tests), anti-heredoc verification, spawn consistency checks, and command structure validation — all passing.

Impact

Users with project-scoped MCP servers: Get a clear, guided migration path instead of mysterious subagent failures. One command (/gsd:migrate-mcp) resolves the issue.
All GSD subagent users: Agents now self-diagnose MCP connectivity issues instead of silently hallucinating. This eliminates a class of hard-to-debug failures where agents return plausible but fabricated MCP data.
No breaking changes: Both additions are purely additive. The <mcp_check> block is a no-op when MCP tools are available. The command is opt-in.
Files changed: 12 files, +249 lines, 0 deletions from existing content

Future Considerations

Claude Code #13898 resolution: When the upstream bug is fixed, /gsd:migrate-mcp becomes optional (nice-to-have convenience rather than required workaround). The <mcp_check> blocks remain useful as defense-in-depth regardless.
mcpServers: frontmatter for project agents: Users with project-specific custom agents (.claude/agents/) can add mcpServers: directly to their frontmatter today. This doesn't help GSD's globally-installed templates but is a valid approach for per-project agents.
/gsd:health --mcp-check: A future health command could auto-detect whether #13898 is fixed by testing MCP propagation to a subagent, eliminating the need for users to know about the bug at all.
Dynamic frontmatter injection: If Claude Code adds support for runtime frontmatter generation, GSD could dynamically inject the user's MCP server list into agent definitions at spawn time, removing the need for global scope migration entirely.

Addresses: BUG-5 (Global MCP Migration Helper), MCP Connectivity Pre-Check
Upstream: Claude Code #13898

Add 'never use heredoc' instruction to 6 agents that were missing it: gsd-codebase-mapper, gsd-debugger, gsd-phase-researcher, gsd-project-researcher, gsd-research-synthesizer, gsd-roadmapper. All 9 file-writing agents now consistently prevent settings.local.json corruption from heredoc permission entries (GSD gsd-build#526). Read-only agents (plan-checker, integration-checker) excluded as they cannot write files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add skills: field to all 11 agent frontmatter files with forward-compatible GSD workflow skill references (silently ignored until skill files are created). Add commented hooks: examples to 9 file-writing agents showing PostToolUse hook syntax for project-specific linting/formatting. Read-only agents (plan-checker, integration-checker) skip hooks as they cannot modify files. Per Claude Code docs: subagents don't inherit skills or hooks from the parent conversation — they must be explicitly listed in frontmatter. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace general-purpose workaround pattern with named subagent types: - plan-phase: researcher and planner now spawn as gsd-phase-researcher/gsd-planner - new-project: 4 researcher spawns now use gsd-project-researcher - research-phase: researcher spawns now use gsd-phase-researcher - quick: planner revision now uses gsd-planner - diagnose-issues: debug agents now use gsd-debugger (matches template spec) Removes 'First, read agent .md file' prompt prefix — named agent types auto-load their .md file as system prompt, making the workaround redundant. Preserves intentional general-purpose orchestrator spawns in discuss-phase and plan-phase (auto-advance) where the agent runs an entire workflow. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Document analysis of Claude Code mcpServers frontmatter behavior based on official documentation. Key finding: frontmatter mcpServers creates independent connections but cannot solve GSD's problem because agent definitions are generic templates, not project-specific. Strategy decision: proceed with MCP migration helper (PR-6) as the practical solution. General-purpose fallback (PR-5) deprioritized. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

New test suite covering: - HDOC: anti-heredoc instruction present in all 9 file-writing agents - SKILL: skills: frontmatter present in all 11 agents - HOOK: commented hooks pattern in file-writing agents - SPAWN: no stale workaround patterns, valid agent type references - AGENT: required frontmatter fields (name, description, tools, color) 509 total tests (462 existing + 47 new), 0 failures. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add /gsd:migrate-mcp slash command that reads project .mcp.json, displays configured servers, and offers to merge them into ~/.claude/mcp.json (global scope). This provides the primary workaround for Claude Code bug #13898 where project-scoped MCP servers don't propagate to custom subagents. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add <mcp_check> block to every agent that instructs them to verify MCP tool availability before use, report clearly when unavailable instead of hallucinating results, and reference /gsd:migrate-mcp as the fix. Placed after </project_context> or </role> depending on agent structure. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Tibsfox · 2026-03-03T08:40:24Z

Code Logic Verification of PR #1

PR: feat: add MCP migration helper and subagent connectivity pre-check
Branch: fix/mcp-migration-helper → dev-bugfix
Commits: 3addc10 (migrate-mcp command, +117 lines) + f32bfa1 (mcp_check blocks, +12 lines × 11 agents)

1. The Before State (Bug Path)

Claude Code bug #13898 prevents project-scoped MCP servers (.mcp.json) from propagating to custom subagents. The execution path before this PR:

User configures MCP servers in .mcp.json (e.g., Context7 for library docs)
GSD spawns a subagent (e.g., gsd-phase-researcher with tools: mcp__context7__*)
Subagent attempts mcp__context7__resolve-library-id → fails silently
Agent has zero fallback logic — no instructions for what to do when MCP is unavailable
Agent may hallucinate MCP results or fail with cryptic errors
No migration path exists for users to move servers to global scope

Affected agents: Primarily gsd-phase-researcher and gsd-project-researcher (which declare mcp__context7__* in frontmatter tools), but all 11 agents could encounter MCP references in user tasks.

2. The After State (Fix Path)

The PR applies a belt-and-suspenders approach: fix the root cause (migration command) + add runtime resilience (pre-check blocks).

Component A — commands/gsd/migrate-mcp.md (+117 lines)

New user-facing command /gsd:migrate-mcp with a 5-step guided process:

Read .mcp.json from project root → early exit if missing/empty
Parse and display server list in table format with status
Read ~/.claude/mcp.json → categorize servers as ADD / SKIP (identical) / CONFLICT
Merge and write using the Write tool (explicitly mandates: "ALWAYS use the Write tool — never use heredoc")
Verify by reading back the written file and displaying final status

Edge cases handled: missing .mcp.json (early exit), no global config yet (starts with {"mcpServers": {}}), name collisions (CONFLICT category with per-server user decision: overwrite/keep/skip), already-migrated servers (SKIP with "identical" note).

Component B — <mcp_check> blocks (12 lines × 11 agents)

Identical block inserted in all 11 agents/gsd-*.md files, placed after <role> or <project_context> (whichever is last), before workflow content. The block instructs agents to:

Check MCP tool availability before using them
Report clearly if unavailable (with bug reference and fix instruction)
Never hallucinate MCP results
Continue without MCP using alternative tools (Read, Bash, WebSearch)

Block placement verified via MD5 checksum — all 11 are byte-identical. Architecturally correct: fires after identity/context, before workflow execution.

3. Key Correctness Checks

#	Check	Result	Notes
1	Block placement consistency	✅ PASS	All 11 agents, identical content, correct ordering
2	Command YAML frontmatter	✅ PASS	Follows GSD command format
3	5-step process logic	✅ PASS	Handles missing files, conflicts, already-migrated
4	No unintended file changes	✅ PASS	Exactly 12 files, 249 insertions, 0 deletions
5	GSD architectural alignment	✅ PASS	Follows existing structural patterns
6	Write tool mandated for config	✅ PASS	Step 4 explicitly requires Write tool
7	Conflict detection	✅ PASS	NEW/SKIP/CONFLICT categorization
8	Bug reference accuracy	✅ PASS	Correctly references #13898
9	Bash in allowed-tools	⚠️ CONCERN	Read tool handles missing files — Bash not strictly needed
10	No backup before global write	⚠️ CONCERN	Should backup `~/.claude/mcp.json` before overwriting
11	MCP check wording	⚠️ CONCERN	"attempt to list or call" could trigger side effects — safer to just check tool listings
12	Blanket application to all agents	⚠️ CONCERN	Only 2-3 agents declare MCP tools; others get unused context
13	Missing AskUserQuestion tool	⚠️ MINOR	Conflict resolution needs interactive input
14	Anti-hallucination guidance	✅ PASS	Addresses real LLM failure mode
15	Graceful degradation	✅ PASS	Correct fail-open to alternative tools

4. Verdict

PASS — The PR addresses a real platform bug (#13898) with a sound two-component architecture: a user-facing migration command that fixes the root cause, plus runtime pre-check blocks that provide graceful degradation. Code trace confirms clean implementation: 12 files, 249 insertions, 0 deletions, consistent block placement, correct architectural ordering.

Noted concerns (non-blocking, suitable for follow-up):

Remove Bash from migrate-mcp allowed-tools (principle of least privilege)
Add backup step before writing ~/.claude/mcp.json
Tighten mcp_check wording to "verify presence in tool listings"
Consider limiting mcp_check to agents that actually declare MCP tools
Add AskUserQuestion to allowed-tools for conflict resolution

These are improvements, not blockers. The current implementation is safe and functional.

Upstream: gsd-build/get-shit-done#814 — open and mergeable.

Verification performed using parallel adversarial review, security analysis, and code trace teams.

- Tibsfox ^.^

… agents Five improvements to the MCP migration helper and agent mcp_check blocks: 1. Add AskUserQuestion to migrate-mcp allowed-tools (needed for conflict resolution prompts) 2. Remove Bash from allowed-tools; reword 3 steps to use Read tool instead of cat commands 3. Add backup step: write ~/.claude/mcp.json.pre-migrate before overwriting existing config 4. Fix mcp_check wording: "check tool listings to confirm accessibility" instead of "attempt to list or call the expected MCP tool" — agents should not invoke MCP tools just to test them 5. Remove mcp_check from 7 agents that never use MCP tools (plan-checker, integration-checker, research-synthesizer, verifier, roadmapper, debugger, codebase-mapper); keep in the 4 that do (planner, executor, phase-researcher, project-researcher) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Tibsfox · 2026-03-03T09:53:08Z

Amendment: Hardening pass on migrate-mcp and mcp_check

New commit 70f7d45 adds 5 improvements identified during code review:

migrate-mcp.md: Added AskUserQuestion to allowed-tools (needed for conflict resolution)
migrate-mcp.md: Removed Bash from allowed-tools; reworded 3 steps to use Read instead of cat
migrate-mcp.md: Added backup step — writes ~/.claude/mcp.json.pre-migrate before overwriting
mcp_check wording: Changed "attempt to list or call the expected MCP tool" → "check tool listings to confirm accessibility — do NOT invoke the tool itself"
mcp_check scope: Removed from 7 agents that never use MCP tools; kept in the 4 that do (planner, executor, phase-researcher, project-researcher)

Net change: -85 lines across 12 files. All 509 tests pass.

— Tibsfox ^.^

Tibsfox and others added 7 commits February 28, 2026 00:35

Tibsfox requested a review from glittercowboy as a code owner February 28, 2026 10:42

Tibsfox mentioned this pull request Mar 3, 2026

fix: add MCP migration helper and subagent connectivity pre-check Tibsfox/get-shit-done#1

Open

9 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add MCP migration helper and subagent connectivity pre-check#814

feat: add MCP migration helper and subagent connectivity pre-check#814
Tibsfox wants to merge 8 commits intogsd-build:mainfrom
Tibsfox:fix/mcp-migration-helper

Tibsfox commented Feb 28, 2026

Uh oh!

Tibsfox commented Mar 3, 2026

Uh oh!

Tibsfox commented Mar 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

Tibsfox commented Feb 28, 2026

Summary

Root Cause

Fix

1. /gsd:migrate-mcp command (commands/gsd/migrate-mcp.md, +117 lines)

2. MCP connectivity pre-check in all 11 agents (+12 lines each, +132 lines total)

Relationship to Other PRs

Testing

Manual Test Plan

Regression Test Suite

Impact

Future Considerations

Uh oh!

Tibsfox commented Mar 3, 2026

Code Logic Verification of PR #1

1. The Before State (Bug Path)

2. The After State (Fix Path)

3. Key Correctness Checks

4. Verdict

Uh oh!

Tibsfox commented Mar 3, 2026

Amendment: Hardening pass on migrate-mcp and mcp_check

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

1. `/gsd:migrate-mcp` command (`commands/gsd/migrate-mcp.md`, +117 lines)